home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / raytrace / pov / gen / rayscene / rayscene.doc < prev    next >
Text File  |  1991-12-12  |  14KB  |  331 lines
  1.  
  2.              Rayscene - Ray Tracer Scene Generator, Version 1.33
  3.              ===================================================
  4.  
  5.     This is Rayscene, small, but very useful utility for raytracer users.
  6.    Rayscene is designed to take advantage of raytracers when creating ani-
  7.    mation scenes. It's machine independent and it doesn't care, which ray-
  8.    tracer you are using. It's very easy to configure to meet your needs.
  9.  
  10. 1. INTRODUCTION
  11.  
  12.     Smooth animation is not very easy to create with raytracers, if you are 
  13.    using PD-software like DKB,QRT,VORT,DBW etc...For example, you want to 
  14.    create animation scene where camera moves round some object. Take out your 
  15.    calculator and calculate values, then create 500 data-files, and finally 
  16.    insert values. Then create script, which renders all pictures. After ren-
  17.    dering, change pictureformat to another format. What a waste of time.
  18.     Rayscene offers good solution to problem. Lets do that animation again 
  19.    with Rayscene. You want to change coordinates of view_point so that ca-
  20.    mera circles around your object:
  21.  
  22.    1. Replace values with variable-names:
  23.    
  24.       VIEW_POINT <0.0 0.0 0.0>
  25.   
  26.       -> VIEW_POINT <#xcoordinate# #this is ycoordinate# #z#>
  27.  
  28.    2. Create a little program, which outputs values of sin/cos and redirect 
  29.       them to file. Let's suppose, "range" is a name of a program, which out-
  30.       puts values of sin/cos:
  31.  
  32.       range > array.arr
  33.  
  34.    3. Edit array.arr. Insert variable names:
  35.  
  36.       1.324 2.234 #this is comment# 3.345 4.336 4.456  ....
  37.  
  38.       -> xcoordinate/this is ycoordinate/z,5
  39.          1.324 2.234 #this is comment# 3.345 4.336 4.456  ....
  40.  
  41.    4. Write a little script, which calculates one picture. After that, chan-
  42.       ge picture format:
  43.  
  44.       dkbtrace +q9 +a +t +i#.dat +o#.tga
  45.       tga2ppm <#.tga | ppmquant 256 |ppmtogif > #.gif
  46.   
  47.  
  48.    5. Use rayscene to create five hundred scenes.
  49.  
  50.       rayscene -ddata -aarray -c500 -sscript
  51.  
  52.     What happens?  Rayscene replaces all variable names with values and 
  53.    then creates 500 data-files. After that it invokes ScriptGenerator, 
  54.    which creates new script, which consists:
  55.  
  56.      dkbtrace +q9 +a +t +idatax.dat +odatax.tga
  57.      tga2fbm <datax.tga | fbquant 256 |fbmtogif > datax.gif
  58.      dkbtrace +9 ....
  59.  
  60.    where x is current scene-number (1-500). After that, just start script 
  61.    or bat, and rendering and format-changing is done automatically.
  62.    Result is animation (500 pictures), where camera moves smoothly using 
  63.    sin/cos values. Notice, that you can use same variables for example to 
  64.    move object when same values are used to move camera.
  65.  
  66. NOTICE: All marks # / etc are easy to change, if you want to use other marks.
  67.  
  68. 2. CONFIGURATION
  69.  
  70.     Rayscene should be very easy to configure. Just edit rayscene.h and re-
  71.    place default values. After that compile source files again. Makefiles 
  72.    for Unix, Microsoft C and Amiga are included.
  73.  
  74. 3. OPTIONS
  75.  
  76.    Rayscene (current version) has following options (options may begin with
  77.   - or / or + or whatever letter...also letters may be upper or lowercase).
  78.   Options and short help are displayed if you write only "rayscene" without 
  79.   any parameters.
  80.  
  81.   -Dname   Input data-name and no extension. Extension is defined in rayscene.h
  82.            Edit it if you want to change default extension and compile rayscene
  83.            again.
  84.   
  85.   -Aname   Input array-name. Rayscene tries to find varible-values from that
  86.            file. Default name is "array" ( so, use only "-a"), if you want to
  87.            change it, edit rayscene.h and compile rayscene again.
  88.  
  89.   -Ccount  Number of scenes to create. There is no default value for that.
  90.  
  91.   -Sname   Script-name for ScriptGenerator. If you don't give name, you can
  92.            type your own script. Generator invokes editor, which is by default
  93.            "me" (MicroEmacs). Edit your script, and save it. Generator reads
  94.            script-file, and replaces all '#'s (defined in rayscene.h) with 
  95.            current file_name.
  96.           
  97.  
  98.   -Iname   This option ensures, that comments in your data file do not effect
  99.            to Rayscene. Name is raytracer name. This option effects only, if
  100.            you have variable names inside comments. For example:
  101.             
  102.               { #Ping# was here before #Pong# }
  103.             
  104.            Rayscene gives error message, if you have values only for Pong. If
  105.            you define /Idkb, comments are skipped. Now supporting DKB,VORT,QRT.
  106.  
  107.   -Nx      Type of output-names. For example Autodesk Animator provides very  
  108.            easy way of loading files, when they end with numbers. Types are:
  109.            /NA    ->  if count is 100, first name is data001.dat, last data100
  110.            /NN    ->  if count is 100, first name is data1.dat, last data100
  111.            Default is /NN.
  112.  
  113.            NOTICE:Make sure, that last letter of original data_file_name is
  114.            not number.
  115.  
  116.   -Oname   If you want different name to your data-files, use this option. 
  117.            This option defines new output name for scene-files. Extension is
  118.            defined in rayscene.h, if you want to change it, edit rayscene.h
  119.            and compile rayscene again.
  120.  
  121.   -Uname  If datafile, arrayfile and outpufile have same name, use this option.
  122.             "Rayscene -utest -c20" 
  123.           is synonyme to 
  124.             "Rayscene -atest -dtest -otest -c20".
  125.           This option does not change script's filename. You can still cheat
  126.           a bit:
  127.             "Rayscene -utest -oshadow -c20"
  128.           is synonyme to
  129.             "Rayscene -atest -dtest -oshadow -c20"
  130.  
  131.   -Rx,x1  Create only requested scenes. For example /r1,5 would create only
  132.           scenes 1-5. Overrides -C option.
  133.  
  134.   
  135. 4. ARRAY-FILE
  136.  
  137.     Array file includes values for variables.  Rayscene scans through this
  138.     file, reads values for all used variables and replaces data file's
  139.     variable names with their values when generating new data/scene files.
  140.     Array file can include data for more variables than is actually used, 
  141.     only those that are referenced in data file are read into memory. 
  142.     The sequence of variables in array file is not important.  
  143.     
  144.     Each variable can have more values than is used.  Rayscene uses the 
  145.     first values and skips those that are not needed.  The format of an 
  146.     array file is quite free: extra white space is allowed in most places 
  147.     and comments can be included if needed.  
  148.     
  149.     File consists of variable groups.  Group consists of group header 
  150.     followed by the values of group's variables.  There can be one or several
  151.     variables in a group.  Below is a short example of an array file:
  152.     -----------------------------------------------------------------------
  153.     Var1/Var2/Var3/LastVariable,3  # <-- This is the header part.
  154.                                      Variable names of a group are 
  155.                                      separated by a '/'.  After the last 
  156.                                      variable name there must be a ','
  157.                                      followed by the number of values
  158.                                      for each variable.
  159.                                    #
  160.     
  161.     1 2 3 4  # first values for each variable #
  162.     5 6      
  163.     7.0 8.0     # second values #
  164.     9 10 11 12  # third values #
  165.     
  166.     Variable5,10
  167.     
  168.     1 2 3 #<- 3rd value # 4 5 6 7 8 9 10  # these are the values for
  169.                                             Variable5   
  170.                                           #
  171.     -----------------------------------------------------------------------
  172.     A comment starts with a '#' and ends when another one is encountered.
  173.     It can be as long as you wish.  You can have comments between group 
  174.     header and it's values.  Also, there can be comments between values
  175.     with different index.  What does that mean? To illustrate this, see 
  176.     the example above:
  177.     In the first group, there can be comments between numbers 4 and 5 
  178.     because 4 = LastVariable[1] and 5 = Var1[2].  There can't be a comment
  179.     between numbers 3 and 4 because 3 = Var3[1] (Variable indexes are the
  180.     same).  Did you understand? I hope so.. ;)
  181.     
  182.     Variable names can be up to 40 characters by default.  Should you need
  183.     longer names, just change MAX_VAR_LENGTH in rayscene.h and recompile.
  184.     Names aren't case sensitive.
  185.  
  186. 5. DATA-FILE
  187.  
  188.      Rayscene is used to replace values from ascii-data file. As mentioned
  189.     before, all variable_names will be replaced (except if /I-option is 
  190.     used).
  191.      Version 1.33 has opne new feature which lets you make simple calcula-
  192.     tions before replace. You can use -+/* to change replaced value.
  193.    
  194.     VIEWPOINT < 0 #y-axis#+100 0 > (y-axis+100)
  195.     VIEWPOINT < 0 #y-axis#-100 0 > (y-axis-100)
  196.     VIEWPOINT < 0 #y-axis#*100 0 > (y-axis*100)
  197.     VIEWPOINT < 0 #y-axis#/100 0 > (y-axis/100)
  198.  
  199.     NOTICE: No blanks between #+100 ! Do not use "# + 100"!    
  200.  
  201. 6. SCRIPTS
  202.  
  203.      When you start rendering your pictures, you can use script making all
  204.     commands for you. But if you just created 500 scene, who's gonna write
  205.     that script?
  206.      Rayscene has one neat feature, called ScriptGenerator. Use it to make
  207.     a dirty work for you. For example, you want to create a script, which
  208.     renders picture, then changes it's format and finally, adds it to zoo
  209.     archive:
  210.      
  211.      dkbtrace +w640 +h480 +q9 +a +t -v +itest.dat +otest.tga
  212.      tga2fbm <test.tga | fbquant -c256 -G >test.gif
  213.      zoo a test.zoo test.gif
  214.      
  215.      That might do it? Sure, but you still have 499 scenes to go...
  216.     Ok, let's use ScriptGenerator. Before you launch rayscene, create
  217.     that script as:
  218.  
  219.      dkbtrace +w640 +h480 +q9 +a +t -v +i#.dat +o#.tga
  220.      tga2fbm <#.tga | fbquant -c256 -G >#.gif
  221.      zoo a test.zoo #.gif
  222.      
  223.  
  224.      Save your script to file "testscr.bat" (for example), and launch
  225.     Rayscene with command 
  226.     
  227.     "rayscene -dtest -avalues -c500 -stestscr"
  228.      
  229.     *OR*
  230.     
  231.      You can use one little shortcut. Give command
  232.      
  233.     "rayscene -dtest -avalues -c500 -s"
  234.     
  235.     After creating 500 scripts, Rayscene will open your editor to create that
  236.     script. Save it, and Rayscene replaces all #-marks with current file_name.
  237.     
  238.      After rayscene you will have file testscr.new, which will consist 500
  239.     duplicates of your script. #-marks are replaced by current file_name.
  240.     
  241.  
  242. 7. NOTES,HINTS
  243.  
  244.      Written in C, should be portable very easily to every environment. Be-
  245.     fore compiling, edit rayscene.h to meet your needs (variable length, 
  246.     default filenames/extensions...etc). When compiling, define environment 
  247.     ie -DIBMPC, -DUNIX and -DAMIGA..etc (if not using included makefiles). 
  248.      If you define file_name_length 8 (as it is in PC), and create 100 scenes 
  249.     with name "testing", name is cut ie. 10th output-name is testin10, or if 
  250.     you have defined /NA, testi010.
  251.  
  252.  
  253. 8. EXAMPLES
  254.  
  255.     rayscene -ainput -dvalues -c200 -s -na
  256.  
  257.     - Get raytracer-data from input.dat and values from values.arr. Create
  258.       200 scenes and use editor to create script. First scene name is 
  259.       input001.dat. Without -na it would be input1.dat.
  260.  
  261.     rayscene -utest -c20 
  262.     
  263.     - Use name "test" for datafile, arrayfile and outputfile. Create 20 scenes
  264.     
  265.     rayscene -utest -c20 -scalc 
  266.     
  267.     - Same as above, but use old script "calc" to create new script. More
  268.       about scripts in Chapter 5.
  269.       
  270.     rayscene -d -a -c120
  271.     
  272.     - Use default names (defined in rayscene.h) and create 120 scenes.
  273.      
  274.   
  275. 9. FUTURE
  276.  
  277.      If you liked or are going to use Rayscene, please register. That DOES 
  278.     NOT mean, you have to send us money (who would send us 20 finnish marks??),
  279.     but it ensures that you get the next version ( or information about it). 
  280.     Also comments and suggestions for future versions are always welcome! If 
  281.     you have something in our mind, send your idea or your code to us...
  282.  
  283.  Registration form is very simple.
  284. ------------------------------------------------------------------------------ 
  285. Name:                                                   
  286. Company:                                                
  287. Street address:
  288. City/Code/Country:
  289.  
  290. Machine/operating system/purpose of using/what raytracer,...etc:
  291.  
  292.  
  293.  
  294. Comments, future enhancements:
  295.  
  296.  
  297.  
  298. -------------------------------------------------------------------------------
  299. Mail Your form to:
  300. Hole@rieska.oulu.fi or 
  301. Oldfox@rieska.oulu.fi
  302.  
  303.  
  304.     
  305.  
  306.  
  307. COPYRIGHT: Still, this is our code! That does not mean, it's piece of art. But
  308.            it means, we have made it. This code is not for commercial use. You
  309.            are encouraged to give it to your friends, but not to take any money.
  310.  
  311.            If you would like to change it, change it, but leave our names to 
  312.            source code, and put your name and little description under subject
  313.            HISTORY. Also, if you add some neat new features, inform US, so we 
  314.            could put it to next version. Enjoy...
  315.          
  316.  
  317. BUGS: Don't end your original data_file_name with number. For example, if
  318.       you have name "simple1.dat", and max_name_length is 8
  319.       -> The first output_name is simple11.dat and 11th is simple11.dat
  320.       (because Rayscene cuts filename if it is longer than max_file_name)
  321.  
  322. Jari Kähkönen (PC)             Panu Hassi (AMIGA)
  323. Hole@tolsun.oulu.fi            Oldfox@tolsun.oulu.fi
  324.  
  325.  
  326.   
  327.  
  328.  
  329.  
  330.  
  331.